Bulk Replace Subscriber Package

This API allows the replacement of an existing package for multiple subscribers in a single call. The process is conducted as a transaction: it first detaches the existing package and then attaches the new package. If the attachment of the new package fails, the detachment will not take effect.

The system enables users to replace packages ('Sell Package') for their sub-customers' subscribers and to replace packages created by their parent customer ('Buy Package') for their own subscribers in a self-service mode. However, self-service package replacement is permitted only if the parent customer has granted permission to the specific sub-customer by activating the 'allowOfferDelegation' flag.

NOTE: The system enables the user to replace an attached package with the same one.

Method Path
POST api/v2/bulk/subscriber/package/replace

Eligibility

The requestor is eligible to replace packages for sub-account subscribers. It is not permitted to replace packages for their own subscribers unless the requestor parent customer:

• Has granted permission by enabling the ‘allowOfferDelegation’ parameter.

• Has included the requestor in the attached package’s ‘eligibleSubAccountIds’ attribute.

• Has assigned at least one package to the requestor.

API Request

Request Structure

Parameter Type M/O/CM Description
bulk Object M Array of main request body objects.

Bulk

Parameter Type M/O/CM Description
subscriberIdentifiers Object M Subscriber unique keys object, defining the search criteria.
content Object M Main elements container object.

subscriberIdentifiers

Parameter Type M/O/CM Description
type String M Defines the search criteria. Valid type ENUMs are: ‘IMSI’, ‘ICCID’, ‘MSISDN’, ‘IMEI’, ‘IMEISV’.
value String M Type value. IMSI or ICCID or MSISDN or IMEI or IMEISV number.

Content

Parameter Type M/O/CM Description
currentPackageId UUID M Existing catalog package ID
newPackageId UUID M New requested catalog package ID
myPackage Boolean O

Determines whether to detach one of the customer’s packages (Sell Packages) from sub-account subscribers or one of the customer’s parent packages (Buy Packages) from own subscribers.

  • True = Request to detach a parent package (my package) from own subscribers. This ‘self-service’ functionality is allowed only in cases where the sub-customer has been defined by its parent customer as allowed to delegate parent customer packages [allow_offer_delegation = true].
  • False = Request to detach one of the customer’s packages (Sell Packages) from sub-account subscribers (normal operation). The default value, if not provided, is ‘false’.

API Response

Response Structure

Parameter Type M/O/CM Description
bulk Object M Array of main response body objects.
pageable Object O Paging information object. Displayed when an API call is successful. For a failure, it will be empty.

Bulk

Parameter Type M/O/CM Description
errorCode String O Failure code.
errorMessage String O Failure detailed description.
requestId UUID CM Request instance ID. To be used by external systems to query the call (operation) status, whether in progress, successful, or failed. Displayed when an API call is successful. For a failure, it will be empty.
subscriberIdentifiers Object M Subscriber unique keys object, defines the search criteria.
content Object M Main response body object. Reflects a single node of the original request.

subscriberIdentifiers

Parameter Type M/O/CM Description
type String M Defines the search criteria. Valid type ENUMs are: ‘IMSI’, ‘ICCID’, ‘MSISDN’, ‘IMEI’, ‘IMEISV’.
value String M Type value. IMSI or ICCID or MSISDN or IMEI or IMEISV number.

content

Parameter Type M/O/CM Description
currentPackageId UUID M Existing catalog package ID
newPackageId UUID M New requested catalog package ID
myPackage Boolean O

Determines whether to detach one of the customer’s packages (Sell Packages) from sub-account subscribers or one of the customer’s parent packages (Buy Packages) from own subscribers.

  • True = Request to detach a parent package (my package) from own subscribers. This ‘self-service’ functionality is allowed only in cases where the sub-customer has been defined by its parent customer as allowed to delegate parent customer packages (allow_offer_delegation = true).
  • False = Request to detach one of the customer’s packages (Sell Packages) from sub-account subscribers (normal operation) The default value, if not provided, is ‘false’.

Pageable

Parameter Type M/O/CM Description
page Numeric M Page number
size Numeric M Page size. Number of requested elements per page
totalPages Numeric M Total amount of available pages per requested page size
totalElements Numeric M Total amount of retrieved elements

Error Codes

In addition to the general success and failure codes, the following error codes are possible per each of the ‘Bulk’ array elements.

Code Message
GLOBAL_1001 Service unavailable. Please try again
SUBSCRIBER_1060 Failed to replace packages
AUTH_1021 You are not eligible to use the self-service mode

Examples

Request Body

Copy 
{
  "bulk": [
    {
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961859"
      },
      "content": {
        "currentPackageId": "4543dedb-cce7-4bee-89f3-7af1447927e6",
        "newPackageId": "7c903dbc-7b6a-4ff4-91f8-96fd38feaa62"
      }
    },
    {
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000034535"
      },
      "content": {
        "currentPackageId": "e7fcef24-5c03-41dd-9e33-995b7d6f47e2",
        "newPackageId": "9a00e612-b17f-492b-a1c9-bf0bf7b3156b",
        "myPackage": true
      }
    }
  ]
}
Response Body – Full Success:

Response Body Full Success ACK

Copy 
{
  "bulk": [
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "currentPackageId": "4543dedb-cce7-4bee-89f3-7af1447927e6",
        "newPackageId": "7c903dbc-7b6a-4ff4-91f8-96fd38feaa62",
        "myPackage": false
      }
    },
    {
      "errorCode": "",
      "errorMessage": "",
      "requestId": "7e74dce6-8eef-4c86-a4bb-1a860913c271",
      "subscriberIdentifiers": {
        "type": "ICCID",
        "value": "8935711001000035687"
      },
      "content": {
        "currentPackageId": "e7fcef24-5c03-41dd-9e33-995b7d6f47e2",
        "newPackageId": "9a00e612-b17f-492b-a1c9-bf0bf7b3156b",
        "myPackage": true
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}

Response Body Includes Failure NAK

Copy 
{
  "bulk": [
    {
      "errorCode": "AUTH_1021",
      "errorMessage": "You are not eligible to use the self-service mode",
      "requestId": "",
      "subscriberIdentifiers": {
        "type": "IMSI",
        "value": "222013090961963"
      },
      "content": {
        "currentPackageId": "e7fcef24-5c03-41dd-9e33-995b7d6f47e2",
        "newPackageId": "9a00e612-b17f-492b-a1c9-bf0bf7b3156b",
        "myPackage": true
      }
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}